Conventionally, application programming interfaces (APIs) are frequently used in software systems to interface different software modules for performing various tasks and/or functions, such as installing packages, building systems, etc. In general, information about the APIs is provided every time an API is called. Specifically, comments are inserted into programming code where an API is called to describe what the API does, arguments to be taken, and output structure of the API. These comments in programming code are generally intended to be read by humans and are ignored by computing machines during compilation of the programming code.
To create documentation on the programming code, conventional scripts and/or tools are used to go through the programming code and extract these comments from the programming code. For instance, a script may simply extract the comments and output the comments extracted as plaintext into a text file, which may be used as the documentation on the programming code.
One problem with the above conventional approach is that the formatting of the documentation is done within the programming code itself. If one wants to change the way it looks, he/she needs to go into the programming code to change the comments inserted in the programming code.
Another problem with the above approach is the lack of consistency. Typically, many people (commonly referred to as programmers) are involved in writing the programming code and the way each programmer writes the comments about the same API may vary. For instance, different vocabularies may be used to describe the function of the same API. In another instance, different programmers may put the same description of an API into different formats. Such inconsistency in documentation may eventually lead to great confusion among users of the APIs.
Another problem with the above approach is the difficulty in updating the documentation. As mentioned above, the APIs are typically called many times in the programming code and comments about the APIs are inserted into the programming code every time the APIs are called. In order to update the documentation of an API, one has to go through the entire programming code to identify all calls of the API and then make the same change in all comments associated with the API in the programming code. This is generally a tedious and error-prone process.